Two commits. The first returns the distance a vector query ranked by; the second makes that query answerable from the vector index instead of a full scan.

1. Return the distance

A vector query could only tell a caller the order rows came back in. getVectorDistanceOrder() computed the distance into the ORDER BY clause and threw it away, and the existing tests only ever asserted on result order, never on a value.

That means there is no way to read a similarity score out of find(). It rules out any relevance-score UI, and it rules out a caller thresholding its own results ("only matches above 0.8"), because top-N is the only handle available.

The distance is now projected alongside the row and hydrated onto the document as Database::VECTOR_DISTANCE ($distance):

$results = $database->find('words', [
    Query::vectorCosine('embedding', $target),
    Query::limit(1000),
]);

$similarity = 1 - $results[0]->getAttribute(Database::VECTOR_DISTANCE);

The value is the raw output of the operator the query ordered by: cosine gives 1 - similarity, euclidean gives L2, dot gives the negative inner product. Kept raw rather than normalised to a 0-1 score so that one invariant holds: $distance always agrees with the position the row was returned in. Negating the dot product to make "higher is better" would break that.

Non-finite distances

Cosine distance to a zero vector divides by a zero magnitude, and a large vector can overflow, so pgvector answers NaN. Previously that NaN only ever lived inside ORDER BY and never crossed into PHP. Projecting it surfaced a real failure:

unexpected NAN value was coerced to string
  src/Database/PDOStatement.php:109
  src/Database/Adapter/SQL.php  ($stmt->fetchAll())

That takes down the entire query, not just the one value. testVectorAllZeros, testVectorCosineSimilarityDivisionByZero and testVectorLargeValues all caught it.

The projected copy is therefore carried as text and interpreted during hydration, so a distance with no value reads back as null. Note the alternative is worse than an error: a plain (float) cast turns 'NaN' into 0.0, which tells the caller the two vectors are identical. There is a test pinning that.

2. Let the index answer the query

find() appends $sequence to the order attributes whenever nothing unique is already ordering the result. A vector index holds one sort key, so a second one does not merely make the index look expensive, it makes it unusable — there is no way to satisfy "distance, then sequence" from a structure that only knows distance.

Every vector search was therefore reading the whole collection and sorting it. Measured on 50k rows of 300 dimensions with an hnsw_cosine index, top-25:

The tie break exists to hold a page boundary still across a cursor, so it is kept when a cursor is present and dropped otherwise. Ties in a float distance over a real embedding are close to unreachable, and an approximate index is free to answer them in either order regardless.

3. Match read permissions against the row instead of joining

Every read resolved permissions through a semi join against the collection's permissions table. A join has to be resolved before anything can be ordered, so whenever the ordering could have come from an index, the planner read the whole collection instead. That is what kept a document-secured vector search on a sequential scan no matter how large the collection got.

The row already carries the same fact. _permissions is written alongside the permissions table on create, bulk create and update, and find() already reads it back to answer $permissions. It simply was not queryable: TEXT, unindexed, output only. Making it JSONB with a GIN index turns a fact we already store into one the planner can cost against the ordering. This is the shape the Mongo adapter has always used, where _permissions is matched inside the document rather than joined.

Measured end to end through find(), 400k rows of 300 dimensions, document security on, top-25:

It also degrades correctly. A permissive permission is a cheap filter over whichever index the ordering wanted; a selective one drives from the GIN index and sorts the small matching set exactly. The planner picks between them because both predicates are finally on the same relation.

Containment (@>) rather than jsonb's ?| key operator, one per role. PDO reads a lone ? as a positional placeholder and refuses to mix it with named ones, and the ?? escape breaks once a named placeholder repeats, which the cursor conditions do. jsonb_exists_any expresses the test in a single call but is not an indexable clause and falls back to reading the table; @> is answered as a BitmapOr across roles.

Postgres only. The other adapters keep the semi join, so nothing about their plans changes. Matching is byte exact in both forms (verified: the existing _permission column has no COLLATE and the database collation is en_US.utf8, so it was already case sensitive, as @> is), so no permission that resolved before resolves differently now.

Safe to do as a plain schema change because Postgres has no users yet, so there is nothing to migrate.

What this still does not fix

Forcing an HNSW scan under a selective filter remains unsafe in general: the scan emits at most hnsw.ef_search candidates (40 by default) and stops, so on 20k rows with 100 readable a forced index scan returns 0 of 25 rows, silently. hnsw.iterative_scan (pgvector 0.8, off by default) fixes that. This is not reachable through normal planning today, before or after these changes: with a selective indexed filter the planner uses that index and sorts exactly, and with an unindexed filter at 1% or 99% selectivity it sequentially scans and sorts, returning 25 of 25 every time. The short read only appears when the index is forced, which the library never does. Worth knowing before anyone reaches for enable_seqscan.

Tests

testVectorDistance in tests/e2e/Adapter/Scopes/VectorTests.php, 32 assertions:

• exact values against hand-computed geometry: identical → 0.0, orthogonal → 1.0, opposite → 2.0, and cosine ignores magnitude where euclidean does not
• distances are non-decreasing across the result set, so the number cannot disagree with the order
• all three metrics, including that <#> returns the negative inner product
• a find() with no vector query carries no $distance
• the value survives Query::select(), which builds a different projection
• an undefined distance is null, not a number

testVectorSearchUsesTheIndex in tests/e2e/Adapter/PostgresTest.php asserts the index is actually scanned, by reading the pg_stat_user_indexes scan counter across the query rather than by inspecting the emitted SQL. It prices sequential scans out of the session first, so it distinguishes the index cannot answer this ordering from the planner found something cheaper, which also keeps it independent of row count.

Every part was verified red before being fixed:

Full e2e suites green: Postgres 659, MySQL 658, MariaDB 658, SQLite 658, unit 409. Pint PSR-12 and PHPStan level 7 clean.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Vector search results now include distance metadata to help assess relevance.
  • Distance values are supported consistently for cosine, Euclidean, and dot-product searches.
  • Distance information is available alongside selected result fields.
  • Vector searches preserve accurate distance-based ordering.
  • Permission-filtered searches use optimized database indexing for improved performance.

• Bug Fixes

  • Non-numeric or unavailable distances are safely returned as null.
  • Improved handling of zero-vector cosine searches and queries without distance data.